import { Badge } from '@theme';

# output

## mode

<Badge text="V1.2.4 新增" type="tip" />

- **类型：** `"normal" | "brief"`

Rsdoctor 报告模式，默认是 `normal`。

- **normal:** 在构建产物目录中生成一个 `.rsdoctor` 文件夹，其中包含各种数据文件，并在报告页面中展示代码。输出目录可以通过 [reportDir](#reportdir) 进行配置。
- **brief:** 在构建产物目录的 `.rsdoctor` 文件夹中生成一个 HTML 报告文件，所有构建分析数据会整合注入到这个 HTML 文件中，可以通过浏览器打开该 HTML 文件查看报告。brief 模式还有更多配置项，详细信息请参阅：[brief](#brief)。

:::tip
mode 是没有 lite 配置项的，lite 模式即将废弃，参考 [lite 模式废弃说明](./options-v2.mdx#lite-模式废弃说明)。
:::

## options

<Badge text="V1.2.4 新增" type="tip" />

- **类型：** `BriefModeOptions | NormalModeOptions`
- **可选：** `true`
- **默认值：** `undefined`
- **描述：**
  根据不同的 `mode` 配置，`options` 支持不同的配置项：

### mode: 'brief'

Brief 模式用于生成轻量级的分析报告，支持 HTML 和 JSON 两种输出格式。

- **`type`**：输出类型，支持 `'html'` 和 `'json'` 数组，可同时选择多种格式
  - 如果配置了 `['html', 'json']`，则会生成一个 html 文件，同时生成一个 json 文件。
  - 如果配置了 `['json']`，则会生成一个 json 文件。文件名为 `rsdoctor-data.json`。
  - 如果配置了 `['html']`，则会生成一个 html 文件。文件名可通过 `htmlOptions.reportHtmlName` 配置。
- **`htmlOptions`**：HTML 输出相关配置
  - **`reportHtmlName`**：HTML 报告文件名，默认为 `report-rsdoctor.html`
- **`jsonOptions`**：JSON 输出相关配置
  - **`sections`**：JSON 输出包含的模块配置
    - **`moduleGraph`**：是否包含模块图数据，默认为 `true`
    - **`chunkGraph`**：是否包含 Chunk 图数据，默认为 `true`
    - **`rules`**：是否包含规则数据，默认为 `true`

**注意事项：**

- Brief 模式下，**`reportCodeType`** 配置项无效，因为只支持 **`'noCode'`**。

**配置示例：**

```js
new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      // 同时输出 HTML 和 JSON 格式
      type: ['html', 'json'],
      htmlOptions: {
        reportHtmlName: 'my-report.html',
      },
    },
  },
});
```

#### HTML 与 JSON 输出格式的区别

| 特性           | HTML 格式                                                | JSON 格式                                                 |
| -------------- | -------------------------------------------------------- | --------------------------------------------------------- |
| **文件结构**   | 单文件，包含完整的分析报告页面                           | 纯数据文件，需要配合客户端使用                            |
| **使用方式**   | 可直接在浏览器中打开查看                                 | 需要上传到 Playground 或配合客户端解析                    |
| **数据完整性** | 包含所有分析数据和可视化界面                             | 仅包含原始分析数据                                        |
| **文件大小**   | 较大（包含样式和脚本）                                   | 较小（仅数据）                                            |
| **适用场景**   | • 离线查看报告<br/>• 直接分享给他人<br/>• 不需要二次处理 | • 上传到 Playground<br/>• 程序化处理<br/>• 数据分析和集成 |
| **依赖关系**   | 无外部依赖，自包含                                       | 需要 Rsdoctor 客户端支持                                  |

> Playground 查看分析报告，详见 [Playground](/guide/start/playground)。

**配置示例对比：**

```js
// 仅生成 HTML 报告（适合离线查看）
new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      type: ['html'],
      htmlOptions: {
        reportHtmlName: 'build-report.html',
      },
    },
  },
});

// 仅生成 JSON 数据（适合上传到 Playground）
new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      type: ['json'],
    },
  },
});

// 同时生成两种格式（适合不同使用场景）
new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      type: ['html', 'json'],
      htmlOptions: {
        reportHtmlName: 'build-report.html',
      },
    },
  },
});
```

### mode: 'normal'

Normal 模式下的 `options` 为空对象，无额外配置项。

### 类型定义

#### BriefModeOptions

```ts
interface BriefModeOptions {
  /** 输出类型，支持 HTML 和 JSON */
  type?: Array<'html' | 'json'>;
  /** HTML 输出相关配置 */
  htmlOptions?: BriefConfig;
  /** JSON 输出相关配置 */
  jsonOptions?: JsonOptions;
}

interface BriefConfig {
  /** HTML 报告文件名，默认为 report-rsdoctor.html */
  reportHtmlName?: string;
  /** 是否额外生成 JSON 数据文件，默认为 false */
  writeDataJson: boolean;
}

interface JsonOptions {
  /** JSON 输出包含的模块配置 */
  sections?: JsonSectionOptions;
}

interface JsonSectionOptions {
  /** 是否包含模块图数据，默认为 true */
  moduleGraph?: boolean;
  /** 是否包含 Chunk 图数据，默认为 true */
  chunkGraph?: boolean;
  /** 是否包含规则数据，默认为 true */
  rules?: boolean;
}
```

#### NormalModeOptions

NormalModeOptions 目前类型为空 Object。

## reportCodeType

- **类型：** `"noModuleSource" | "noAssetsAndModuleSource" | "noCode" | { noModuleSource?: boolean; noAssetsAndModuleSource?: boolean; noCode?: boolean }`
  - **V2 时，类型将只支持 String 类型。**
- **可选：** `true`
- **默认值：** `undefined`，undefined 时输出所有完整数据。
- **描述：**
  选择输出的分析数据范围：
  - **默认**：输出所有完整数据
  - **`noModuleSource`**：输出除模块（[Module](https://rspack.rs/config/module#module)）代码外的数据，模块（[Module](https://rspack.rs/config/module#module)）代码即产物（（[Module](https://rspack.rs/config/module#module)））内各个文件的打包模块代码
  - **`noAssetsAndModuleSource`**：输出除模块（[Module](https://rspack.rs/config/module#module)）代码和 Assets 产物代码外的数据
  - **`noCode`**：输出除代码外的数据，即不输出任何代码

### 输出数据对比表

| 配置项                      | 包含的数据                                                                               | 不包含数据                                                  | 适用场景                                                               | 文件大小 |
| --------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- | -------- |
| **默认** (不配置)           | **完整构建信息：**<br/>• Modules 数据及其打包后代码<br/>• Assets 代码<br/>• 其他分析数据 | 无                                                          | • 开发调试<br/>• 完整分析                                              | 最大     |
| **noModuleSource**          | • 构建信息<br/>• Modules 数据及其打包后代码<br/>• Assets 代码<br/>• 其他分析数据         | Modules 源代码                                              | • 不需要查看源代码<br/>• 发生内存泄漏问题                              | 中等     |
| **noAssetsAndModuleSource** | • 构建信息<br/>• Modules 数据及其打包后代码<br/>• 其他分析数据                           | Module 源代码、Assets 代码                                  | • 大型项目<br/>• 不需要查看源代码和 Assets 代码<br/>• 发生内存泄漏问题 | 较小     |
| **noCode**                  | • 构建信息<br/>• Modules 数据<br/>• 其他分析数据                                         | 所有代码（Module 源代码 + Module 打包后代码 + Assets 代码） | • 大型项目<br/>• CI/CD<br/>• 发生内存泄漏问题                          | 最小     |

**数据输出从丰富到简的排序：** `默认` > `noModuleSource` > `noAssetsAndModuleSource` > `noCode`

> Asset 和 Module 解释，见[术语](./term)

- **示例：**

```js
new RsdoctorRspackPlugin({
  reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true }
}),
```

## reportDir

- **类型：** `string`
- **可选：** `true`
- **默认值：** `undefined`

Rsdoctor 报告输出目录，默认是构建产物输出目录。

## compressData

:::warning
V2 中即将废弃，请使用 `output.mode: 'brief'` 和 `output.options.type: 'json'` 代替。参考 [compressData 配置迁移](/config/options/options-v2#compressdata)。
:::

- **类型：** `boolean`
- **可选：** `true`
- **默认值：** `true`

compressData 用于配置是否将 `[outputDir]/.rsdoctor` 下的分析数据进行压缩处理。
